package com.beauty.product.service;

import com.beauty.product.dto.CategoryDto;

import java.util.List;

/**
 * 商品分类服务接口
 * <p>
 * 定义了商品分类管理相关的所有业务操作，包括分类的创建、查询、更新、删除等功能，
 * 以及分类树的构建和按不同条件（层级、父分类等）检索分类的方法。
 * </p>
 * 
 * @author beauty-dev
 * @version 1.0
 */
public interface CategoryService {
    
    /**
     * 创建新分类
     * 
     * @param categoryDto 分类数据传输对象，包含分类的详细信息
     * @return 返回创建成功的分类信息
     */
    CategoryDto createCategory(CategoryDto categoryDto);
    
    /**
     * 根据ID获取分类详情
     * 
     * @param id 分类ID
     * @return 返回指定ID的分类详细信息
     */
    CategoryDto getCategoryById(Long id);
    
    /**
     * 根据分类名称获取分类详情
     * 
     * @param name 分类名称
     * @return 返回指定名称的分类详细信息
     */
    CategoryDto getCategoryByName(String name);
    
    /**
     * 获取所有根分类
     * <p>
     * 根分类是指没有父分类的顶级分类
     * </p>
     * 
     * @return 返回所有根分类列表
     */
    List<CategoryDto> getRootCategories();
    
    /**
     * 获取指定父分类下的所有子分类
     * 
     * @param parentId 父分类ID
     * @return 返回指定父分类下的所有子分类列表
     */
    List<CategoryDto> getSubcategories(Long parentId);
    
    /**
     * 获取指定层级的所有分类
     * 
     * @param level 分类层级，1表示一级分类，2表示二级分类，以此类推
     * @return 返回指定层级的所有分类列表
     */
    List<CategoryDto> getCategoriesByLevel(Integer level);
    
    /**
     * 获取所有分类列表
     * <p>
     * 返回扁平化的分类列表，不包含层级关系
     * </p>
     * 
     * @return 返回所有分类的列表
     */
    List<CategoryDto> getAllCategories();
    
    /**
     * 获取分类树结构
     * <p>
     * 返回完整的分类树结构，包含父子关系，从根分类开始
     * </p>
     * 
     * @return 返回分类树结构
     */
    List<CategoryDto> getCategoryTree();
    
    /**
     * 更新分类信息
     * 
     * @param id 分类ID
     * @param categoryDto 更新的分类信息
     * @return 返回更新后的分类详情
     */
    CategoryDto updateCategory(Long id, CategoryDto categoryDto);
    
    /**
     * 删除分类
     * <p>
     * 如果分类下有子分类，可能会导致删除失败
     * </p>
     * 
     * @param id 要删除的分类ID
     */
    void deleteCategory(Long id);
} 